\input{team-manual-preamble}

\usepackage[english]{babel}

% For inclusion of the correct date (last modified)
\SVN $Date: 2009-10-14 12:28:44 +0200 (Wed, 14 Oct 2009) $
\SVN $Revision: 2911 $

\title{\DOMjudge team manual}

\hypersetup{
	pdftitle={DOMjudge team manual},
	pdfauthor={DOMjudge Developers: domjudge-devel at lists.a-eskwadraat.nl},
	pdfsubject={Instruction for teams using the interface of the DOMjudge jury system during a programming contest},
	pdfkeywords={DOMjudge,manual,team,judge,jury,programming,contest,icpc,acm}
}

\begin{document}

\titlestuff{\DOMJUDGEVERSION}{\SVNRevision}{\SVNDate}{\today}

\section*{Summary}

Here follows a short summary of the system interface. This is meant as
a quick introduction, to be able to start using the system. It is,
however, strongly advised that at least one of your team's members
reads all of this manual. There are specific details of this
jury system that might become of importance when you run into
problems. \textbf{BE WARNED!}

DOMjudge works through a web interface that can be found at\\
\url{\WEBBASEURI team}.

\subsection*{Reading and writing}

Solutions have to read all input from `standard in' and write all
output to `standard out' (also known as console). You will never have
to open (other) files. See appendix~\ref{codeexamples} for some
examples.

\subsection*{Submitting solutions}

You can submit solutions with%
\ifcmdsubmit{ the command-line program \cmd{submit} or by}
the web interface:
\begin{description}[\breaklabel\setlabelstyle{\bfseries}]
\ifcmdsubmit{
\item[Command-line]
Use \cmd{submit <problem>.<extension>}, where \cmd{<problem>} is the
label of the problem and \cmd{<extension>} is a standard extension for
your language.  For a complete reference of all options and examples,
see \cmd{submit --help}.
}
\item[Web interface]
From your team page, \url{\WEBBASEURI team}, browse to
\textbf{submit} and select the file you want to submit. By default,
the problem is selected from the base of the filename and the language
from the extension.
\end{description}

\subsection*{Viewing scores, submissions, etc.}

Viewing scores, submissions and sending and reading clarification
requests is done through the web interface. The menu buttons at
\url{\WEBBASEURI team} speak for themselves.

\emph{End of summary}

\newpage

\section{Submitting solutions}\label{submit}

\ifcmdsubmit{
Submitting solutions can be done in two ways: with the command-line
program \cmd{submit} or using the web interface. One of the
interfaces might not be available, depending on the system
configuration by the jury. A description of both methods follows.

\subsection{Command-line: \cmd{submit}}

\textbf{Syntax:} \cmd{submit [options] filename.ext}

The submit program takes the name (label) of the problem from
\cmd{filename} and the programming language from the extension
\cmd{ext}. This can be overruled with the options
\cmd{-p problemname} and \cmd{-l~languageextension}.
See \cmd{submit --help} for a complete list of all options,
extensions and some examples.  Use \cmd{submit~--help | more}
when the help text does not fit on one screen.

\cmd{submit} will check your file and warns you for some problems:
for example when the file has not been modified for a long time or
when it's larger than the maximum source code size.

Then \cmd{submit} displays a summary with all details of your
submission and asks for confirmation. Check whether you are submitting
the right file for the right problem and language and press `y' to
confirm. \cmd{submit} will report a successful submission or give
an error message otherwise.

The submit program uses a directory \cmd{\USERSUBMITDIR} in the
home directory of your account where it stores temporary files for
submission and also a log file \cmd{submit.log}. Do not remove or
change this directory, otherwise the \cmd{submit} program might fail to
function correctly. Furthermore a ``public ssh-key'' of the jury might have
been added to the \textsc{ssh} configuration; this is also necessary
for the functioning of \cmd{submit}.
}

\subsection{Web interface}

Solutions can be submitted from the web interface at \url{\WEBBASEURI team}.
Navigate to \textbf{submit} to select the file for submission, and the
problem and language. These can also be left on the default
`automatic' setting; then the problem and language will be determined
from the base and extension of the filename respectively.

After you hit the submit button and confirm the submission, a page is
shown with a confirmation of successful upload. Next, you should be
able to see the submission in your submissions list.

\section{Viewing the results of submissions}

There is an overview of your submissions on your team web page.
It contains all relevant information: submission time, programming
language, problem and status. The address of your team page is
\url{\WEBBASEURI team}. From here you can also view the public
scoreboard page with the scores of all teams.

\subsection{Possible results}

A submission can have the following results:

\begin{description}[\setleftmargin{4.5cm}]
\item[CORRECT]
The submission passed all tests: you solved this problem!

\item[COMPILER-ERROR]
There was an error when compiling your program. On the submission
details page you can inspect the exact error (this option might be
disabled).

\item[TIMELIMIT]
Your program took longer than the maximum allowed time for this
problem. Therefore it has been aborted. This might indicate that your
program hangs in a loop or that your solution is not efficient
enough.

\item[RUN-ERROR]
There was an error during the execution of your program. This can have
a lot of different causes like division by zero, incorrectly
addressing memory (e.g. by indexing arrays out of bounds), trying to
use more memory than the limit, etc.
Also check that your program exits with exit code 0!

\item[NO-OUTPUT]
Your program did not generate any output. Check that you write to
standard out.

\item[WRONG-ANSWER]
The output of your program was incorrect. This can happen simply
because your solution is not correct, but remember that your output
must comply exactly with the specifications of the jury.

\item[PRESENTATION-ERROR]
The output of your program has differences in presentation with the
correct results (for example in the amount of whitespace). This will,
like WRONG-ANSWER, count as an incorrect submission. This result is
optional and might be disabled.

\item[TOO-LATE]
Bummer, you submitted after the contest ended! Your submission is
stored but will not be processed anymore.
\end{description}

\section{Clarifications}

All communication with the jury is to be done with clarifications.
These can be found on your team page. Both clarification replies from
the jury and requests sent by you are displayed there.

There is also a link to submit a new clarification request to the
jury. This request is only readable for the jury and they will respond
as soon as possible. Answers that are relevant for everyone will be
sent to everyone.

When you receive a new clarification from the jury, this will
automatically be displayed as ``(1 new)'' in the clarification button
in the menu bar. This will be updated automatically even without reloading
the page.

\section{How are submissions being judged?}

The \DOMjudge jury system is fully automated. In principle no human
interaction is necessary. The judging is done in the following way:

\subsection{Submitting solutions}

With%
\ifcmdsubmit{ the \cmd{submit} program or}
the web interface (see section~\ref{submit}) you can submit a solution
to a problem to the jury. Note that you have to submit the source code
of your program (and not a compiled program or the output of your
program).

There your program enters a queue, awaiting compilation, execution
and testing on one of the jury computers.

\subsection{Compilation}

Your program will be compiled on a jury computer running Linux.
Using a different compiler or operating system than the jury should
not be a problem. Be careful however, not to use any special compiler
and/or system specific things (you may be able to check compiler errors
on the team page).

\subsection{Testing}

After your program has compiled successfully it will be executed and
its output compared to the output of the jury. Before comparing the
output, the exit status of your program is checked: if your program
gives the correct answer, but exits with a non-zero exit code, the
result will be a \textsc{run-error}! There are some restrictions during
execution. If your program violates these it will also be aborted
with a \textsc{run-error}, see section~\ref{runlimits}.

When comparing program output, it has to exactly match to output of
the jury. So take care that you follow the output specifications. In
case of problem statements which do not have unique output (e.g. with
floating point answers), the jury may use a modified comparison
function.

\subsection{Restrictions}\label{runlimits}

To prevent abuse, keep the jury system stable and give everyone
clear and equal environments, there are some restrictions to which all
submissions are subjected:

\begin{description}[\setlabelphantom{number of processes}]
\item[compile time]
Compilation of your program may take no longer than \COMPILETIME\
seconds. After that compilation will be aborted and the result will
be a compile error. In practice this should never give rise to
problems. Should this happen to a normal program, please inform the
jury right away.

\item[source size]
The source code of your program may not exceed \SOURCESIZE\ kilobytes,
otherwise your submission will be rejected.

\item[memory]
During execution of your program, there are \MEMLIMIT\ kilobytes of
memory available. This is the total amount of memory (including
program code, statically and dynamically defined variables, stack,
Java VM, \dots)! If your program tries to use more memory, it will
abort, resulting in a run error.

\item[program output]
You are not allowed to output more than \FILELIMIT\ kilobytes
on either standard out or standard error, and will get a run error
if you exceed this limit.

\item[number of processes]
You are not supposed to create multiple processes (threads). This is
to no avail anyway, because your program has exactly 1 processor fully
at its disposal. To increase stability of the jury system, there is a
maximum of \PROCLIMIT\ processes that can be run simultaneously
(including processes that started your program).

People who have never programmed with multiple processes (or have
never heard of ``threads'') do not have to worry: a normal program
runs in one process.

\end{description}

\subsection{Java class naming}

Compilation of Java sources is somewhat complicated by the class
naming conventions used: there is no fixed entry point; any class can
contain a method \texttt{main}. Furthermore, a class declared
\texttt{public} must be located in an indentically named file.

In the default configuration of DOMjudge this is worked around by
autodetecting the main class. When this feature is not used, then
the main class should be ``\verb!Main!'', with method
``\verb!public static void main(String args[])!'', see also the Java
code example in appendix~\ref{codeexamples}.

\newpage
\appendix

\section{Code examples}\label{codeexamples}

Below are a few examples on how to read input and write output for a
problem.

The examples are solutions for the following problem: the first line
of the input contains the number of testcases. Then each testcase
consists of a line containing a name (a single word) of at most 99
characters. For each testcase output the string ``Hello $<$name$>$!''
on a separate line.

Sample input and output for this problem:

\begin{tabular}{|p{0.47\textwidth}|p{0.47\textwidth}|}
\hline
\textbf{Input} & \textbf{Output} \\
\hline
\verbatiminput{../examples/example.in} &
\verbatiminput{../examples/example.out} \\
\hline
\end{tabular}

Note that the number 3 on the first line indicates that 3 testcases
follow.

A solution for this problem in C:
\listinginput{1}{../examples/example.c}

Notice the last \cmd{return 0;} to prevent a \textsc{run-error}!

\newpage

A solution in C++:
\listinginput{1}{../examples/example.cc}

A solution in Java:
\listinginput{1}{../examples/example.java}

\newpage

A solution in Pascal:
\listinginput{1}{../examples/example.pas}

And finally a solution in Haskell:
\listinginput{1}{../examples/example.hs}

\end{document}
